home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / jpeg / jpgidx13 / jpgindex / english / jpgindex.doc
Text File  |  1993-05-24  |  15KB  |  320 lines
  1. -----------------------------------------------------------------------------
  2.  
  3.                         J P G I N D E X   1 . 3 e
  4.                       _____________________________
  5.                       ~^~^~^~^~^~^~^~^~^~^~^~^~^~^~
  6.  
  7. Copyright (c) 1993 by TBH-Softworx --- all rights reserved
  8.               Oliver Fromme, Klingestr. 2, 38640 Goslar, Germany
  9.               Internet email: inof@asterix.rz.tu-clausthal.de
  10.  
  11.  
  12. For private persons, this program is CARDWARE. You may copy it, use it,
  13. and give it to your friends under the following conditions:
  14.  * Don't charge any money.
  15.  * Keep all the files together.
  16.  * Don't change the files in any way.
  17.  * If you use this program or if you think that it's useful (or both...?),
  18.    please write a postcard (e. g. with a beautiful picture of your home
  19.    town), see my address above. You needn't send money. But if you really
  20.    want to give me some money, please do so...
  21.  
  22. If you're using this program for images on a BBS, Mailbox, ftp-server,
  23. fsp-server, any kind of public software/image library/archive or something
  24. similar, YOU HAVE TO REGISTER JPGINDEX. Just send US$ 20 or DM 20 (cash, no
  25. other currencies, no stamps) to my address (see above). I'll imform you if
  26. there's a newer version of JPGIndex.
  27.  
  28. The JPGIndex software package contains the following files:
  29.    1. README.TXT     -  might contain important news and updates
  30.    2. JPGINDEX.EXE   -  the main program JPGIndex
  31.    3. TGASCALE.EXE   -  a tool to scale targa images
  32.    4. TGAMERGE.EXE   -  a tool to merge targa images together
  33.    5. TGAWRITE.EXE   -  a tool to write into targa images
  34.    6. *.DOC          -  english documentation
  35.    7. *.DOK          -  german documentation
  36.  
  37. ATTENTION:
  38.    Use this software on your own risk!
  39.    I'm not responsible for any damage caused by the use of this software!
  40.    I've tested it intensively, and it seems to work.
  41.    Nevertheless, be careful.
  42.  
  43. JPGIndex needs the programs DJPEG and CJPEG from "The Independent JPEG Group"
  44. (IJG), written by Thomas Lane. They're available from major PD sources.
  45.  
  46. -----------------------------------------------------------------------------
  47.  
  48. What is JPGIndex?
  49. ~~~~~~~~~~~~~~~~~
  50.  
  51. JPGIndex takes some JPEG images (as many as you like), scales them down
  52. (i.e. shrinks them), and merges them together. The resulting image is
  53. called "index image". The input images are called "stamps".
  54.  
  55.  * Input:  Any number of Images (stamps), JPEG format (JFIF standard).
  56.            Greyscale or true colour images. All stamps are equally scaled
  57.            (by the same factor).
  58.  
  59.  * Output: An index image, targa or JPGE format. Greyscale or true colour
  60.            (can be set by the user). The size of the image and the Space
  61.            between the stamps can be set by the user. The filenames are
  62.            written below the stamps. The stamps are sorted by filename
  63.            (optional). A preview of the index image can be displayed
  64.            (optional, VGA needed).
  65.  
  66. JPGIndex is especially useful if you have lots of JPEG images. It's a good
  67. idea to make an index image for every subdirectory.
  68.  
  69. System requirements:
  70.  * AT, 80286 (there are special 386 versions of DJPEG/CJPEG)
  71.  * a harddisk
  72.  * sufficient memory for DJPEG/CJPEG (see IJG documentation)
  73.  * If possible, a large RAM disk (approx. 1 - 3 Mb).
  74.    You should set the environment variable TEMP or TMP in order
  75.    to use the RAM disk.
  76.  
  77. -----------------------------------------------------------------------------
  78.  
  79. Getting started
  80. ~~~~~~~~~~~~~~~
  81.  
  82. The simplest possible usage is the following:
  83.    JPGINDEX .
  84. (Don't forget the ".", it means the current directory.)
  85. Then JPGIndex will search for all JPEG files in the current directory and
  86. read their sizes and colour attributes (greyscale [8 bit] or true colour
  87. [24 bit]). Their names are sorted alphabetically and displayed on the screen.
  88.  
  89. Note: JPGIndex searches for files with an extension of ".JPG".
  90.       If you've got JPEG files with other extensions (e.g. ".JPE" or ".J"),
  91.       you have to specify them, for example
  92.          JPGINDEX *.JPE *.J
  93.       to search for all files with an extension of ".JPE" and ".J".
  94.  
  95. Now JPGIndex tries different scaling factors, until it has found one which
  96. fits best for a 800x600 pixel image. This complicated process may take
  97. several seconds.
  98. If you've got a VGA graphics adapter, JPGIndex now display a preview of
  99. what it has computed. Press any key to return to textmode.
  100.  
  101. Then JPGIndex produces four files:
  102.  * INDEX.BAT    -  A batch file. It will do the complete conversion,
  103.                    scaling and everything else.
  104.  * INDEX.MRG    -  Contains the position data of the stamps (where they're
  105.                    located in the index image). This file is used by
  106.                    INDEX.BAT and should not be edited by the user.
  107.  * INDEX.WRT    -  Contains the position data of the filenames which are
  108.                    written below the stamps. This file is used by INDEX.BAT
  109.                    and should not be edited by the user.
  110.  * CLEANUP.BAT  -  If you're happy with your index image produced by
  111.                    INDEX.BAT, you may call this batch file. It will delete
  112.                    all temporary files (including CLEANUP.BAT itself).
  113. Just type "INDEX" now to start the batch job.
  114.  
  115. Note: The programs DJPEG.EXE, CJPEG.EXE, TGASCALE.EXE, TGAMERGE.EXE, and
  116.       TGAWRITE.EXE must be located somewhere in the path (check your PATH
  117.       environment variable by typing "PATH"). Otherwise INDEX.BAT can't
  118.       find them, which results in an error message. If this is the case,
  119.       You have to look where those programs are, add the directory to your
  120.       PATH environment variable, and call INDEX.BAT again.
  121.  
  122. If INDEX.BAT terminates succesfully (without an error message), there are
  123. two more files: INDEX.TGA and INDEX.JPG. The JPEG image is compressed using
  124. a quality value of 75. If you don't like the quality setting, just use
  125. CJPEG to compress INDEX.TGA again with better quality (see the documentation
  126. from IJG).
  127. If you think that IMAGE.JPG looks ok, you may call CLEANUP.BAT. It will
  128. delete all temporary files, including all remaining targa files and
  129. CLEANUP.BAT itself.
  130.  
  131. Once again, step by step:
  132.  1. Run JPGIndex. You can specify any number of images and directories on
  133.     the command line.
  134.  2. Check the preview. If you don't like it, call JPGIndex with different
  135.     options (see below).
  136.  3. Run INDEX.BAT.
  137.  4. Check INDEX.JPG. If you don't like the quality (or the file size),
  138.     compress it with a different quality setting.
  139.  5. Run CLEANUP.BAT.
  140.  6. Be happy.
  141.  
  142. -----------------------------------------------------------------------------
  143.  
  144. Options of JPGIndex
  145. ~~~~~~~~~~~~~~~~~~~
  146.  
  147. This is the complete sytax:
  148.    JPGINDEX files/directories ... [options ...]
  149. Files, directories, and options may appear in any order. If no file extension
  150. is given, ".JPG" is assumed.
  151.  
  152. Version 1.3e supports the following options (not case sensitive):
  153.  
  154.    /Wx   Sets the width of the index image, by default 800 pixel (/W800),
  155.          maximum 2048 pixel. There's no space between /W and x.
  156.          If necessary, JPGIndex reduces the width slightly to improve
  157.          the arrangement of the stamps.
  158.  
  159.    /Hx   Sets the height of the index image, by default 600 pixel (/W600),
  160.          maximum 2048 pixel. There's no space between /H and x.
  161.          If necessary, JPGIndex reduces the height slightly to improve
  162.          the arrangement of the stamps.
  163.  
  164.    /Sx   Sets the space between stamps (vertical and horizontal), by default
  165.          8 pixel (/S8).
  166.  
  167.    /Tx   Sets the space between the stamp and its filename, by default 2
  168.          pixel (/T2).
  169.  
  170.    /G    Forces JPGIndex to produce a greyscale index image. This saves time
  171.          (both when producing the index image, and later when decompressing
  172.          and displaying the index image) and hard disk space.
  173.          If all stamps are greyscale images, JPGIndex will automatically
  174.          produce a greyscale index image. If there's at least one true colour
  175.          stamp, the index will be true colour also (if you don't use this
  176.          option).
  177.          Be careful: some JPEG images are signed as "true colour", but they
  178.                      contain only shades of grey, wasting time and space.
  179.                      You'd better convert them to real greyscale images.
  180.  
  181.    /C    Forces JPGIndex to produce a true colour image, even when all stamps
  182.          are greyscale images. This doesn't make sense, I think.
  183.  
  184.    /D-   Do not display the Preview. This is useful if you already know what
  185.          it will look like.
  186.  
  187.    /N+   Sort the images by filenames. This is also done by default, so you
  188.          don't need this option.
  189.  
  190.    /N-   Don't sort the images by filenames.
  191.  
  192.    /N*   Sort the images in order to optimize the index image. This usually
  193.          produces less "holes" in the index image and a better scaling
  194.          factor.
  195.  
  196.    /A+   Shift stamps vertically to fill holes in the index image, usually
  197.          resulting in a more compact index image. This is done by default if
  198.          /N* is specified. Looks sometimes weird in conjunction with /N- or
  199.          /N+ (ragged bottom border).
  200.  
  201.    /A-   Don't shift stamps vertically (by default if /N* is not specified).
  202.  
  203. -----------------------------------------------------------------------------
  204.  
  205. Important notes
  206. ~~~~~~~~~~~~~~~
  207.  
  208.  * As mentioned above, the programs DJPEG.EXE, CJPEG.EXE, TGASCALE.EXE,
  209.    TGAMERGE.EXE, and TGAWRITE.EXE must be located somewhere in the path
  210.    in order to be found by INDEX.BAT.
  211.  
  212.  * You'd better not edit INDEX.BAT, INDEX.MRG, or INDEX.WRT manually.
  213.    If you are curious, look at them. But be warned, any modification may
  214.    lead to unpredictable results.
  215.  
  216.  * INDEX.BAT must be run in the directory it was produced in by JPGIndex.
  217.    This must also be the current directory. This is a small bug of DJPEG
  218.    and CJPEG (version 4), which refuse to work if the converting files
  219.    are not in the current directory.
  220.  
  221.  * JPGIndex gives a rough approximation of the disk space needed for
  222.    temporary files. There should be enough space on the current drive.
  223.  
  224.  * If your RAM disk is big enough, you should set the environment variable
  225.    TEMP or TMP in order to use the RAM disk. INDEX.BAT will produce the
  226.    targa image there. If your RAM disk is not big enough, let TEMP/TMP
  227.    point to your hard disk.
  228.    For example, if you're making an greyscale index image of 800x600 pixel,
  229.    it will need about 480 Kb (800 multiplied by 600) for the targa image.
  230.    If it's true colour, it needs three times the space (about 1.5 Mb).
  231.  
  232.  * If an error occurs while INDEX.BAT is running (e.g. not enough XMS memory
  233.    for DJPEG, or no space left on the hard disk), a message is displayed and
  234.    INDEX.BAT stops. You may then try to fix the error (free some XMS memory
  235.    or delete some files) and Run INDEX.BAT again. It will continue with
  236.    the picture which produced the error.
  237.  
  238.  * You may also interrupt INDEX.BAT by pressing Ctrl-C or Ctrl-Break.
  239.    To continue, just run INDEX.BAT again. If you want to start from
  240.    the beginning, delete all files with an extension of "*.TGS".
  241.  
  242. -----------------------------------------------------------------------------
  243.  
  244. How it all works
  245. ~~~~~~~~~~~~~~~~
  246.  
  247. (You needn't read this.)
  248.  
  249. This section describes how the index image is produced by INDEX.BAT.
  250.  
  251. For every stamp <name> the following operations are performed:
  252.  * If there's already a file named <name>.TGS, this stamp is skipped.
  253.  * DJPEG is run: it produces <name>.TGA.
  254.  * TGASCALE is run: it reads <name>.TGA and produces <name>.TGS.
  255.  * The file <name>.TGA is deleted.
  256.  
  257. When all stamps have their corresponding .TGS-file, the following is done:
  258.  * TGAMERGE is run with INDEX.MRG as parameter.
  259.    It reads all .TGS-files and produces INDEX.TGA (using the directory
  260.    specified by the environment variable TMP or TEMP, if set).
  261.  * All .TGS-files are deleted.
  262.  * TGAWRITE is run with INDEX.WRT as parameter.
  263.    It writes the filenames into the index image INDEX.TGA.
  264.  * If INDEX.TGA was produce in a different directory, it is now moved to
  265.    the current directory (i.e. copied and then deleted from the original
  266.    directory).
  267.  * CJPEG is run. It reads INDEX.TGA and produces INDEX.JPG. A quality setting
  268.    of 75 is used, which is sufficient in most cases.
  269.  
  270. -----------------------------------------------------------------------------
  271.  
  272. The End
  273. ~~~~~~~
  274.  
  275. This is probably not the last version of JPGIndex. There are many features
  276. I can implement or improve.
  277.  
  278. By the way, there are more targa utilities I have written. They're not
  279. included in this software package because JPGIndex doesn't need them.
  280.  * TGACLIP   -  cuts a part from a targa image.
  281.  * TGACOLOR  -  converts true colour images to greyscale images
  282.                 and vice versa.
  283.  * TGACONTR  -  enables you to chnage contrast, brightness, and colouring
  284.                 of a targa images. Very powerful.
  285.  * TGAMIRR   -  converts images with bottom-up raster to top-down raster.
  286.                 Is also able to mirror an image. For example, "Image Alchemy"
  287.                 produces bottom-up targa images.
  288.  * TGAVIEW   -  displays targa images on most VGA and SuperVGA graphics
  289.                 adapters (greyscale oder true colour using dithering
  290.                 techniques). You can move around with your mouse, display
  291.                 coordinates and "pick colours".
  292.  
  293. How to get the latest version of JPGIndex
  294. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  295.  * If you can access "anonymous ftp", you can get it from the ftp-server
  296.    "ftp.tu-clausthal.de" (139.174.2.10), it is in the directory
  297.    /pub/msdos/graphics.
  298.  * If you can receive email, I can email it to you (uuencoded).
  299.  * I can send it to you via snailmail. Please note that this costs US$ 10 or
  300.    DM 10 (cash, no other currencies, no stamps) to cover my expenses. Don't
  301.    forget to mention the disk format you need. And make sure that there's a
  302.    newer version, otherwise you may get the same version you already have.
  303.  * Please no calls. Mail or email only.
  304.  
  305. I have to mention that...
  306. ~~~~~~~~~~~~~~~~~~~~~~~~~
  307.  * "The Graphics Interchange Format(c) is the Copyright property of
  308.     CompuServe Incorporated.  GIF(sm) is a Service Mark property of
  309.     CompuServe Incorporated."
  310.  
  311.  
  312. Have fun!
  313.       - Olli -
  314.  
  315. -----------------------------------------------------------------------------
  316. Oliver Fromme, Klingestr. 2, 38640 Goslar, Germany
  317. Internet email: inof@asterix.rz.tu-clausthal.de
  318. -----------------------------------------------------------------------------
  319. THIS ROOM IS AIR CONDITIONED -- KEEP WINDOWS CLOSED!
  320.